Dogpaw is a program for displaying and/or printing text files from the BASIC/ProDOS environment. In addition to its intended primary use as a means of presenting on-disk program documentation, I'm sure many will find Dogpaw useful for a variety of other text viewing/printing purposes.
Dogpaw is public domain. Anyone is welcome to use it for any purpose. In particular, you are welcome to include Dogpaw as a part of any software package you may be distributing, regardless of whether your software is public domain or commercial. Just don't charge any money for Dogpaw itself.
When displaying text on-screen, Dogpaw presents the text in word wrapped form on either the 40 or 80 column screen. As you can see if you're reading this from your screen, Dogpaw allows you to page forward and backward through the text. The "previous page" option is often extremely useful, and is a considerable improvement over text-to-screen utilities that only offer one-way scrolling. Dogpaw also has a "search" option which allows you to scan through a file for occurrences of any word or phrase. When the 80 column screen is being used, Dogpaw will show your approximate position in the file with a percentage display at the bottom right of the screen. If Dogpaw detects that it is running on an Apple II+, the on-screen text will be displayed in upper case, with lower case a selectable option.
When being used to print text, Dogpaw prints with a one inch left margin, and has the option of printing a header at the top of each page. This header can be centered if desired, and can include the page number. While Dogpaw is printing, the number of the page being sent to the printer is displayed on-screen, and the user can pause or end the printing at page breaks. This is useful if single sheet paper is being used, and with most systems, by "printing" to a switched-off printer, this feature can be used to start (actual) printing at some given page in the text other than the first. Both the screen-displayed text and the printed text can be set to either single or double spacing.
Dogpaw will work with standard ASCII text files and AppleWorks word processor files. These are listed as types "TXT" and "AWP" in a Basic.System catalog. It also works with "compressed" type files which are created with my Compressor program, which is on the /Doc.Stuff disk, available from me. Compressed files catalog as type "$F8", and are about 30% smaller than equivalent TXT or AWP files; full information is in the Compressor instructions. (And for programmers, Dogpaw can also read APW/Orca SRC files.) Dogpaw will work with files of ANY length, to the maximum allowed by ProDOS. (There are a couple of small qualifications to this; they are explained below under "Notes on minor stuff".) Files that are too long to fit in available memory will be loaded in segments, each segment being loaded as it is needed. For best results, ASCII text files for Dogpaw should only have <return>s at paragraph ends (rather than the end of each line). Most word processors can save text to disk in this format; you may have to select "save as ASCII text file" when saving your text. The file you're reading from now is an AWP file called "DOGPAW.DOCS"
Using Dogpaw:
When you BRUN (or "-") Dogpaw, it installs itself as a new ProDOS command, and can then be used much like other ProDOS commands. (More correctly called "BASIC.SYSTEM commands", if ya wanna get technical.) For example, from the Applesoft prompt, you can simply type in "Dogpaw [filename]", with [filename] being the name or pathname of the text file you want to view. The text will be word wrapped for either 40 or 80 column display, depending on which is active when you call Dogpaw. If Dogpaw finds that the active output slot is neither 0 (40 column display) nor 3 (40 or 80 column) when it is called, it assumes that the output is for a printer, and the text is formatted appropriately. As with other ProDOS commands, Dogpaw can also be used from within a BASIC program in the form: PRINT CHR$(4)"DOGPAW [filename]". Thus, to use Dogpaw to print a file with a printer in slot 1, you would use a BASIC line such as:
Any initialization string your printer or interface card might need should also be entered before calling Dogpaw. When Dogpaw finishes printing the file, it will return to "slot 0"; output to screen in 40 column mode. The STARTUP program on this disk is an example of a fairly complete documentation presentation system, allowing the user to select 40 or 80 column screen, and printer slot number. A program could also be set up to give the user access to the various other options available with Dogpaw, such as entering a string to scan the file for. A "table of contents" menu similar to the one in /DOC.STUFF/'s STARTUP can be used to let the user select from a number of text files. Using Dogpaw and a small BASIC program, you could "publish" an entire book on a 3.5 inch disk. ("DiskTop Publishing"?)
When displaying text, there is a prompt at the bottom of the screen explaining how to move through the text. <Return> displays the next page of text, <space> the previous page, and <esc> exits you from the text display. Additionally, you can press "1" to go back to the beginning of the text, and the up and down arrow keys can be used in place of <return> and <space>.
Here are descriptions of Dogpaw's optional features:
"\" - The page header option:
To have Dogpaw print a header at the top of each printed page, the following syntax is used:
10 PRINT CHR$(4)"DOGPAW [filename]\[header]"
That is, whatever you want printed at the top of your pages is written in after the pathname of the text file, separated from the pathname with a backslash. The header will be printed at the top left of each page. If you want the header centered on the page, separate it from the pathname with TWO backslashes:
DOGPAW [filename]\\[header]
If you want the page number included in your header, insert the "#" character where you want the page number to appear. To have the page number alone appear as a header, simply enter "#" as your header:
DOGPAW [filename]\\#
In the /DOC.STUFF/STARTUP program, the header "Dogpaw Instructions; page #" is used for the file you're reading now. Page headers can be up to 64 characters in length. The header option has no effect on Dogpaw's text-to-screen display.
"$" - The scan/search option:
When using Dogpaw to display text on-screen, you can have it scan through the text until a certain string of characters is found. The syntax for this is much like that for the page header option:
DOGPAW [filename]$[string]
or
10 PRINT CHR$(4)"DOGPAW [filename]$[string]"
With [string] being whatever you want to scan for. If you enter
DOGPAW DOGPAW.DOCS $widget
then Dogpaw will put the file DOGPAW.DOCS on screen, and quickly flip through the pages until a page with the first occurrence of the word "widget" is being displayed. Then you can page forward or backward as usual. If no occurrence of the entered string is found, Dogpaw will scan through to the end of the text, and the "end of text" message will appear at the screen bottom. If, when Dogpaw stops scanning and displays the page of text with your string, you press "S", instead of <space> (for previous page) or <return> (next page), Dogpaw will start scanning again for another occurrence of the string. When using the 80 column screen, Dogpaw will flag the line(s) the string appears in by inversing the first character of the line. The string can be up to 64 characters in length. The search is not case sensitive; entering "cat" will also find "Cat" or "CAT". Including a scan-string in the Dogpaw command line will have no effect if Dogpaw is being used to print the file. The scan/search option can't be used in the same command line with the page header option.
"$$" - The auto-scan option:
If you use two "$" signs to start a scan-string, then the functioning of the scan will change in two respects: First, if Dogpaw should scan through to the end of the file, it will automatically exit from the file, rather than showing the "end of text" message and halting. Second, your Apple will beep when a scan-string is found in the text. The automatic-exit feature allows an Applesoft "shell" for Dogpaw to scan several files for a string, each file in the series being loaded by the shell when the end of the previous one is reached. Because such a multi-file scan might take quite a while, the bell-ring was added to "announce" a successful search.
"+" - The double spacing option:
Normally, Dogpaw displays and prints its text single spaced. If you want a double spaced display or printout, simply include a "+" AFTER the filename, and BEFORE the header or search-string, if either is being used; like so:
DOGPAW [filename]+\[header]
or
DOGPAW [filename]+$[string]
or just
DOGPAW [filename]+
In my opinion, text on the 40 column screen is much easier to read if it's double spaced. A BASIC menu program can be configured to set Dogpaw to double spacing if 40 column display is selected.
"@" - "As-is" mode:
Occasionally, you may want to use Dogpaw to print out a TXT file which has carriage returns inserted at the end of each line, and has the line-length set to 80 columns. This is called "80 column hard formatting". This kind of formatting is often found in text files that are uploaded to Bulletin Board Systems. Because Dogpaw normally does its own word wrapping at 70 columns when it's printing, an 80 column hard formatted file can give you a messy looking printout, with lots of very short lines mixed in with normal-length lines. If you find this happening, you can turn off Dogpaw's 70 column word wrapping and let the file use its own formatting by including "@" (circled "a", for "as-is") after the pathname when calling Dogpaw. Like this:
When this feature is used, Dogpaw will print without a left-hand margin. Using "@" won't effect on-screen text; hard formatted files will look fine on an 80 column display, but will have lots of oddly-lengthed lines on a 40 column display.
"%" - The print alternate pages option:
One of the drawbacks to on-disk program documentation is that printouts of this documentation can be very bulky, compared to printed manuals. This is primarily because the text is printed on only one side of each page. Dogpaw's "%" option provides a simple means of printing a document using both sides of pin-feed computer paper. The syntax of this option is the same as the "+" and "@" options; an example would be:
When this option is in effect, Dogpaw will first print only the odd-numbered pages of the file (1,3,5, etc.). Then it will prompt the user to "Remove, reverse, and restart paper; press <return>" This means to remove the paper that has been printed on and re-insert it into the printer with the back (unprinted) side forward. Press <return>, and Dogpaw will start printing the file again, this time the even-numbered pages. Thus, page 2 will be printed on the back of page 1, page 4 opposite page 3, etc. The printout will then be ready to be "burst" and put in a binder.
The "+", "@", and "%" tokens can be used together in any combination. They can also be used together with either the "\" header option or the "$" scan-string option.
Case-convert for the II+:
When Dogpaw detects that it is running on an Apple II+, the text displayed on-screen will be converted to upper case. To accommodate II+'s that have been modified to display lower case, this conversion can be turned off by pressing "C". Pressing "C" again will turn it back on. When running on a II+, Dogpaw will put a prompt at the bottom of the text-display screen which explains this feature. Text sent to a printer on a II+ will not be converted to upper case. Dogpaw's 80 column mode is compatible with Videx Videoterm standard II+ 80 column cards.
NODOGPAW:
To remove Dogpaw and free up the memory it uses (about 4K), enter "NODOGPAW". After this is done, entering any Dogpaw commands will result in a syntax error. Please note, however, that this command will release all the buffers that any other added ProDOS commands, ampersand ("&") routines, etc. have allocated. (Dogpaw supports daisy-chaining of other added ProDOS commands.) This shouldn't cause any problems with other added ProDOS commands or with ampersand routines - they will simply be removed and disconnected along with Dogpaw. Problems could be caused, however, if NODOGPAW is used when certain other buffer-allocating programs are installed. Some such programs don't use either the ampersand or the added-command "hooks". The NODOGPAW command will release the memory set aside for routines like these, but won't "disconnect" them. Therefor, a crash becomes likely. In general, you should avoid using NODOGPAW unless you are sure that nothing that will cause problems is tucked away in the machine's memory.
DOGPAW?:
Entering "DOGPAW?" will display the title, version number and date of the Dogpaw program, and also the name and address of its glory-hogging author (me). This is handy for checking whether Dogpaw is installed. This same information is printed whenever you BRUN Dogpaw in immediate mode (that is, from the keyboard, not from within a BASIC program).
Notes on minor stuff:
The text-to-screen "previous page" function of Dogpaw works with all files, including those that are large enough that they have to be loaded in segments. This means that you could "next page" from the beginning to the end of a (say) 200K file, and then "previous page" your way back to the beginning again. However, when using "previous page" with files that have to be loaded in segments, the exact layout of the pages will not always be preserved. For example, you may find that the bottom line of a "previous" page was the top line of the page you "previous paged" from. (Normally, there isn't any overlap.) This is a result of Dogpaw's having to estimate how far to back up to display the previous page. It shouldn't cause any problems.
Limits: Due to the methods Dogpaw uses to translate AppleWorks AWP files and compressed-type files to normal text, full end-to-beginning previous-paging of these files will not work with files that require more than 20 segment-loads to reach the end of the file. Since around 30K is loaded in each segment (depending on the memory used by any loaded BASIC program), it's unlikely that anyone will be inconvenienced by this. As with type TXT files, Dogpaw can page forward through AWP and compressed files indefinitely. Another "limit" on file size is Dogpaw's printout page numbering option, which can't go above 9,999 pages.
When using Dogpaw to send text to a printer, it's generally best to activate the printer (with PRINT CHR$(4)"PR#1", for slot 1) from 40 column mode. If the Apple is in 80 column mode, the 80 column firmware should be turned off with a PRINT CHR$(21) or <esc> <control-Q> before activating the printer. It's usually a good idea to do this before any printer use from BASIC, with or without Dogpaw.
When printing, Dogpaw will ignore any embedded printer-control characters, AppleWorks margin and New Page settings, etc. There are a couple of AppleWorks formatting features that Dogpaw will respond to correctly, however. One is the line-centering option entered into an AppleWorks document with open-apple-O and CN. The other is the tab-ruler settings available in AppleWorks version 3.0 and later.
Dogpaw BLOADs at $4000, and relocates itself above HIMEM, which is lowered accordingly. Before relocating itself, Dogpaw checks to see if it has already been installed. If it has, it simply returns to BASIC, rather than installing a second copy of itself. When loading a text file into memory, Dogpaw will use whatever room is unused by the BASIC program (if any) that's loaded. Dogpaw will return standard Basic.System error messages to let you know if things go wrong. S(lot) and D(rive) parameters are supported; an example of the correct syntax using these would be:
DOGPAW [filename],S6,D1+$[scan-string]
I'd like to thank Garry Delong and Doug Trueman for their help with Dogpaw. Without their assistance, Dogpaw would be a mere bug-eaten shell of its current self.
Why "Dogpaw"? - thought you'd never ask. Very simple, actually: Start with "Documentation; Printer or Screen". Shorten that to "Doc.P.O.S." Now give that a couple of hard shakes & a slap, and VOILA! You get "Dogpaw". Obvious, huh?
